RLinks
======

This Java ME example application demonstrates how to port a network and
content-intensive utility application from Android to Series 40 touch devices.

The application connects to Reddit, a social news service where 
registered users submit content, typically in the form of a link. Other users 
then rate the submissions, which affects the ranking and position of the posts
on the site's pages and front page.

A simple Android client was first developed and then ported to Series 40.
The user flow of the application is kept as similar as possible to illustrate
the differences. A number of helper classes were included in order to match
the functionality in its Android counterpart.

The clients mostly differ in how the UI is handled: many components used to
show content from Reddit are manually laid out using self-made CustomItems in
LCDUI-based FormViews.

This application demonstrates:
- Handling network connections
- Retrieving and storing data using a JSON REST API
- Laying out custom view items

This example application is hosted in Nokia Developer Projects:
- https://projects.developer.nokia.com/rlinks

The original Android application is hosted in:
- https://projects.developer.nokia.com/reddit_android

For more information on the implementation and porting, visit the wiki pages:
- https://projects.developer.nokia.com/rlinks/wiki


1. Usage
-------------------------------------------------------------------------------

The main MIDlet class is a central point for handling the view logic (using
a variety of Listener classes). The application requires network connectivity
in order to be useful.


2. Prerequisites
-------------------------------------------------------------------------------

- Java ME basics
- Java ME threads
- Java ME networking


3. Project structure and implementation
-------------------------------------------------------------------------------

3.1 Folders
-----------

 |                  The root folder contains the project file, resource files,
 |                  the license information, and this file (release notes).
 |
 |- nbproject       Contains NetBeans project files.
 |
 |- res             Contains application images and other assets.
 |
 |- src             Contains the Java source code files.


3.2 Important files and classes
-------------------------------

| File                           | Description                                |
|--------------------------------|--------------------------------------------|
| \Main.java                     | Control point for the main UI flow,        |
|                                | controlling changes between views using    |
|                                | listeners.                                 |
|--------------------------------|--------------------------------------------|
| ...\network\HttpClient.java    | Base class for networking activities.      |
|                                | Handles network threads and cookies.       |
|--------------------------------|--------------------------------------------|
| ...\network\HttpOperation.java | Base class used by all network operations. |
|                                | Specific methods may be overridden to      |
|                                | achieve the desired functionality.         |
|--------------------------------|--------------------------------------------|


3.3 Used APIs
-------------

Java ME Web Services 1.0
Nokia User Interface 1.7
Nokia Touch UI


4. Compatibility
-------------------------------------------------------------------------------

Nokia Asha software platform and Series 40 touch phones with CLDC 1.1 and
MIDP 2.0.

Tested to work on the Nokia Asha 501, Nokia Asha 311, Nokia Asha 303, Nokia X3-02, and Nokia Asha 308. 
Developed with NetBeans 7.3 and Nokia Asha SDK 1.0.


4.1 Required capabilities
-------------------------

CLDC 1.1, MIDP 2.0, and the APIs listed in Section 3.3.


4.2 Known issues
----------------

- A Reddit account must be created on www.reddit.com to use
  the features requiring authentication (voting and commenting).

- The Reddit API might change unexpectedly. A quote from the API documentation: 
  "Changes to this API can happen without warning. (...) The JSON replies can 
  also change without warning."

- HTTP link URLs contained in comments are currently not accessible.

- As video playback is not possible, the popular "videos" subreddit
  is excluded from the default list of categories

- Scrolling lengthy comments (hundreds of characters) is bound to slow down the
framerate.


5. Building, installing, and running the application
-------------------------------------------------------------------------------

5.1 Preparations
----------------

Before opening the project, make sure that the Nokia SDK 2.0 or newer for Java is 
installed and added to NetBeans.

5.2 Building
------------

The project can be easily opened in NetBeans by selecting 'Open Project'
from the File menu and selecting the application. Building is done by selecting
'Build main project'.

The project can also be built using Eclipse.

5.3 Series 40 device
--------------

Installing the application on a phone can be done by transferring the JAR file
via Nokia Suite or over Bluetooth.

5.4 Emulator
------------

The application can be started in the emulator by selecting 'Run Main Project' 
in NetBeans.


6. Licence
-------------------------------------------------------------------------------

See the licence text file delivered with this project. The licence file is also
available online at
http://projects.developer.nokia.com/rlinks/browser/LICENSE.TXT


7. Related documentation
-------------------------------------------------------------------------------

The Reddit API used is freely available to be used without an API key. The
documentation for the API can be found in GitHub:
- https://github.com/reddit/reddit/wiki/API

Reddit
- http://www.reddit.com/


8. Version history
-------------------------------------------------------------------------------

1.1 Ported to Asha devices.
1.0 Initial release
